Magnum One/Magnum One (Mid-American Digital) (Disc Manufacturing).iso/d12/trace1a.arc/TRACE.DOC

Text File | 1987-02-04 | 8.0 KB | 178 lines

                TRACE - Interrupt Tracer version 1.21 01/26/86

                          Written by Joan Riff for:
                     Computerwise Consulting Services

                 P.O. Box 813, McLean VA 22101  [phone]

               Documented and Enhanced 01/26/87  by A. B. Krueger

        Contact: ARNY KRUEGER at the EXEC-PC BBS in Shorewood Wisconson.


TRACE is a TSR program that traces interupts.

                It:

                 * traps interrupt's
                 * traces the registers at the entry to the interrupt,
                 * executes the interrupt itself
                 * optionally traces the registers at exit from the interrupt.

TRACE also allows the user at the keyboard to display  this traced information,
either on the screen or at the printer.

The interrupt's that are to be traced are specified in the ICT table in the
source code. Once defined, they may be enabled or disabled from the keyboard.
A default ICT is provided and you should not modify it until you understand how
TRACE is used and how it works.

      <<< REBOOT AS SOON AS POSSIBLE AFTER INVOKING TRACE!!! >>>

TRACE is not foolproof or bugfree. Use it as a tool for finding out what DOS
and DOS programs do. You use it at your own risk.  When you have a printout of
the trace activity that interests you, reboot your system.  It may not be long
for this world! Don't say that you weren't warned.


      Usage is: TRACE [size]

          where: size is the size of the trace table in K
                 between 10 and 63, default is 30


Known problems:

   *   Programs that use:  INT 21h function E0h

   *   Relay Gold Release 2.0

   *   Programs that use INT 2Eh

   *   Keyboard ICT control for ICT's 7-15 is flakey



How it works:

   TRACE initialization code is in TRACE12.ASM.  At initialization, TRACE
   initializes its Interrupt Control Table (ICT).  The ICT contains one element
   for every interrupt number or subset thereof to be traced. Tracing control
   within a given interrupt number is determined by the value of AH. Interrupts
   vary as to whether they return to the caller, or not. INT 20 (program exit)
   is an example of an interrupt that does not return to the caller. Treatment
   of the 808x flags at return also varies, and is controlled by the ICT. DOS
   INT 21 function 25 is used to route interrupts to TRACE entry points.

   The ICT entries are laid out in TRACE1E.AIC, and defined in TRACE1.ASM.
   Further documentation about  ICT's is located there, for easy reference.
   There are 16 possible different ICT entries. The first 12 are used, leaving
   4 for future expansion. The first 12 are not sacrosanct, but an entry
   covering INT 21H  0D0h < AH < 0FFh is recommended. TRACE traps  INT 21h to
   protect itself against being loaded twice.

   TRACE allocates a trace table in accordance with the calling parameter.
   If none is provided, 30K is used as a default. The trace table size is
   forced to be between 10K and 64K. If below 10K, the table would be smaller
   than the program that controls it, which makes little sense. The 64K limit
   comes from the 808x segment size.

   When a interrupt to be TRACEd takes place, TRACE stores register and flag
   information in the trace table, with a header that tells what kind of
   interrupt trace entry this is. If post-interrupt tracing is requested, then
   some carry-forward information is placed on the stack, and control is passed
   to the interrupt handler that was in place when TRACE was initialized. After
   the original interrupt handler returns, TRACE stores stores register and
   flag information in the trace table, with a header that tells what kind of
   interrupt trace entry this is. If the interrupt table is full, tracing ends.

   When TRACE is entered via Shift-PrtSC, or from Periscope via INT 60h,
   TRACE's command processor prompts for output and trace control commands,
   which are single letters. One important command is "Q" for QUIT, which
   returns control to DOS. The Output routing options are printer or screen.
   Print output enables displaying TRACE data without affecting the screen's
   display, as well as making hard-copy for reference. The enable and disable
   options allow the status of individual ICT's to be altered. The "T" command
   actually lists the trace, or selected data, by ICT number. The "L" command
   lists the ICT status. The "C" command clears the trace table and ICT count
   fields.

   The ICT for INT 21h subfunctions 00-09 are usually disabled because there
   is a lot of uninformative action in this range, for keyboard and screen I/O.
   It would not be too wise to try to trace INT 10h and 17h, as they are used
   by TRACE.


How and Why to Modify TRACE:

   When TRACE displays trace table data, it is formatted and self-explanitory.
   Each known interrupt is tagged with identifying text, and the register and
   flag contents are labeled and described. Tables in TRACE1.AIC control this
   for interrupts 13H and 21h.  TRACE11.ASM contains most of the formatting
   subroutines and secondary tables.

   Note that TRACE11 contains a PRINT_EDIT subroutine that is capable of
   sophisticated output formatting using flag bytes EDIT_xxxx, which are
   defined in TRACE1E.AIC.

   TRACE1E.AIC changes can affect all three .ASM files. If you change TRACE1E,
   figure on re-assembling TRACE1, TRACE11, and  TRACE12.  Normally, updating
   the TRACE1 ICT definitions necessitates re-assembling only TRACE1. Link
   TRACE using the command:

               LINK TRACE1+TRACE11+TRACE12,TRACE;

   Convert TRACE to a COM file using:

               EXE2BIN TRACE.EXE TRACE.COM


How to use TRACE:

   Initialize TRACE using the command:

                    TRACE

   If TRACE is already in place it will type an error message, but no harm will
   be done.

   When you trace, we encourage you to use the Shift-PrtSc key to interrupt the
   opeation of complex programs, and clear the trace table so that the contents
   of the trace table are relevant to your study. Some programs trap INT 5, and
   will keep you from getting into TRACE using Shift-PrtSc, until they
   complete.

   TRACE has been upgraded to be fairly stable. In its original form Interuupts
   20h, 27h, 21h with AH=31h and 21h with AH=4Ch would cause it to crash often.
   It is your responsibility to alter the operational environment or modify
   TRACE to stay intact through the operation you are TRACing.

   TRACE will impact the performance of  your PC when it is running, especially
   if the trace table is not yet full. It provides a means for understanding
   the control and flow of programs like DOS itself, for which you have no
   source code or internals documentation. One trick is to use TRACE  CS:IP
   values to get a IP value that you subsequently use with DEBUG to trace the
   area of interest.

   Trace information can also be used to find out which program code inspects
   or updates specific parts of a disk that are known to contain information of
   interest.  You may have to work back from an INT 13 or INT 24 entry to do
   this.  You will have to identify the location on disk by drive, side, track,
   and sector number. There are several disk utilities that will help you do
   this such as NORTON's utilities, IBM's DiskRepair, or Central Point's PC
   TOOLs.

   When running TRACE, you may notice a large number of DOS INT 21h AH=3E
   calls as DOS closes file handles 5-19 once per keyboard or .BAT file
   command.  If this bothers you, you can modify the ICT table to disable
   TRACEing this interrupt. Note that there is one pass through TRACE's
   interrupt handlers for every different range of AH you define in the ICT's,
   until the correct ICT is found.

   Any insights about TRACE that you route to the author will be appreciated!
   Contact ARNY KRUEGER at the EXEC-PC BBS, or daytime voice phone
   313-583-9610.